.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "ONEVM" "1" "October 2016" "" "onevm(1) -- manages OpenNebula virtual machines"
.
.SH "NAME"
\fBonevm\fR \- manages OpenNebula virtual machines
.
.SH "SYNOPSIS"
\fBonevm\fR \fIcommand\fR [\fIargs\fR] [\fIoptions\fR]
.
.SH "OPTIONS"
.
.nf

 \-m, \-\-multiple x          Instance multiple VMs
 \-\-hold                    Creates the new VM on hold state instead of
                           pending
 \-\-name name               Name for the new VM
 \-\-cpu cpu                 CPU percentage reserved for the VM (1=100% one
                           CPU)
 \-\-vcpu vcpu               Number of virtualized CPUs
 \-\-arch arch               Architecture of the VM, e\.g\.: i386 or x86_64
 \-\-memory memory           Memory amount given to the VM\. By default the
                           unit is megabytes\. To use gigabytes add a \'g\',
                           floats can be used: 8g=8192, 0\.5g=512
 \-\-disk image0,image1      Disks to attach\. To use an image owned by other
                           user use user[disk]\. Add any additional
                           attributes separated by \':\' and in the shape of
                           KEY=VALUE\. For example, if the disk must be
                           resized, use image0:size=1000 \. Or
                           image0:size=1000:target=vda,image1:target=vdb
 \-\-nic network0,network1   Networks to attach\. To use a network owned by
                           other user use user[network]\. Additional
                           attributes are supported like with the \-\-disk
                           option\.
 \-\-raw string              Raw string to add to the template\. Not to be
                           confused with the RAW attribute
 \-\-vnc                     Add VNC server to the VM
 \-\-vnc\-password password   VNC password
 \-\-vnc\-listen ip           VNC IP where to listen for connections\. By
                           default is 0\.0\.0\.0 (all interfaces)\.
 \-\-vnc\-keymap keymap       VNC keyboard layout
 \-\-spice                   Add spice server to the VM
 \-\-spice\-password password spice password
 \-\-spice\-listen ip         spice IP where to listen for connections\. By
                           default is 0\.0\.0\.0 (all interfaces)\.
 \-\-spice\-keymap keymap     spice keyboard layout
 \-\-ssh [file]              Add an ssh public key to the context\. If the file
                           is omited then the user variable SSH_PUBLIC_KEY
                           will be used\.
 \-\-net_context             Add network contextualization parameters
 \-\-context line1,line2,line3 Lines to add to the context section
 \-\-boot device_list        Set boot device list e\.g\. disk0,disk2,nic0
 \-\-files_ds file1,file2    Add files to the contextualization CD from
                           thefiles datastore
 \-\-init script1,script2    Script or scripts to start in context
 \-\-startscript [file]      Start script to be executed
 \-\-report_ready            Sends READY=YES to OneGate, useful for OneFlow
 \-\-dry                     Just print the template
 \-a, \-\-append              Append new attributes to the current template
 \-\-schedule TIME           Schedules this action to be executed afterthe
                           given time\. For example: onevm resume 0
                           \-\-schedule "09/23 14:15"
 \-t, \-\-type type           Type of the new Image
 \-s, \-\-snapshot snapshot   ID of the Snapshot to save\.
 \-\-hard                    Does not communicate with the guest OS
 \-e, \-\-enforce             Enforce that the host capacity is not exceeded
 \-\-live                    Do the action with the VM running
 \-\-success                 Recover a VM by succeeding the pending action
 \-\-failure                 Recover a VM by failing the pending action
 \-\-retry                   Recover a VM by retrying the last failed action
 \-\-interactive             Enables interactive recovery\. Only works
                           alongside the \-\-retry option\.
 \-\-delete                  No recover action possible, delete the VM
 \-\-recreate                No recover action possible, delete and recreate
                           the VM
 \-f, \-\-file file           Selects the template file
 \-i, \-\-image id|name       Selects the image
 \-t, \-\-target target       Device where the image will be attached
 \-\-cache cache_mode        Hypervisor cache mode: default, none,
                           writethrough, writeback, directsync or unsafe\.
                           (Only KVM driver)
 \-\-discard discard_mode    Hypervisor discard mode: ignore or unmap\. (Only
                           KVM driver)
 \-\-prefix prefix           Overrides the DEV_PREFIX of the image
 \-n, \-\-network id|name     Selects the virtual network
 \-i, \-\-ip ip               IP address for the new NIC
 \-l, \-\-list x,y,z          Selects columns to display with list command
 \-c, \-\-listconf conf       Selects a predefined column list
 \-d, \-\-delay x             Sets the delay in seconds for top command
 \-f, \-\-filter x,y,z        Filter data\. An array is specified with
                           column=value pairs\.
 \-\-csv                     Write table in csv format
 \-x, \-\-xml                 Show the resource in xml format
 \-n, \-\-numeric             Do not translate user and group IDs
 \-k, \-\-kilobytes           Show units in kilobytes
 \-\-describe                Describe list columns
 \-\-all                     Show all template data
 \-\-persistent              Make the new images persistent
 \-v, \-\-verbose             Verbose mode
 \-h, \-\-help                Show this message
 \-V, \-\-version             Show version and copyright information
 \-\-user name               User name used to connect to OpenNebula
 \-\-password password       Password to authenticate with OpenNebula
 \-\-endpoint endpoint       URL of OpenNebula xmlrpc frontend
.
.fi
.
.SH "COMMANDS"
.
.IP "\(bu" 4
create [\fIfile\fR] Creates a new VM from the given description instead of using a previously defined template (see \'onetemplate create\' and \'onetemplate instantiate\')\.
.
.IP "" 4
.
.nf

Examples:

  \- using a template description file:

    onevm create vm_description\.tmpl

  \- new VM named "arch vm" with a disk and a nic

    onevm create \-\-name "arch vm" \-\-memory 128 \-\-cpu 1 \-\-disk arch \e
                 \-\-network private_lan

  \- a vm with two disks

    onevm create \-\-name "test vm" \-\-memory 128 \-\-cpu 1 \-\-disk arch,data
valid options: multiple, hold, name, cpu, vcpu, arch, memory, disk, nic, raw, vnc, vnc_password, vnc_listen, vnc_keymap, spice, spice_password, spice_listen, spice_keymap, ssh, net_context, context, boot, files_ds, init, startscript, report_ready, dry
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
update \fIvmid\fR [\fIfile\fR] Update the user template contents\. If a path is not provided the editor will be launched to modify the current content\. valid options: append
.
.IP "\(bu" 4
hold \fIrange|vmid_list\fR Sets the given VM on hold\. A VM on hold is not scheduled until it is released\. It can be, however, deployed manually; see \'onevm deploy\'
.
.IP "" 4
.
.nf

States: PENDING
valid options: schedule
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
release \fIrange|vmid_list\fR Releases a VM on hold\. See \'onevm hold\'
.
.IP "" 4
.
.nf

States: HOLD
valid options: schedule
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
disk\-saveas \fIvmid\fR \fIdiskid\fR \fIimg_name\fR Saves the specified VM disk as a new Image\. The Image is created immediately, and the contents of the VM disk will be saved to it\.
.
.IP "" 4
.
.nf

States: ANY
valid options: type, snapshot
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
terminate \fIrange|vmid_list\fR Terminates the given VM\. The VM life cycle will end\.
.
.IP "" 4
.
.nf

With \-\-hard it unplugs the VM\.

States: valid if no operation is being performed on the VM
valid options: schedule, hard
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
undeploy \fIrange|vmid_list\fR Shuts down the given VM\. The VM is saved in the system Datastore\.
.
.IP "" 4
.
.nf

With \-\-hard it unplugs the VM\.

States: RUNNING
valid options: schedule, hard
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
poweroff \fIrange|vmid_list\fR Powers off the given VM\. The VM will remain in the poweroff state, and can be powered on with the \'onevm resume\' command\.
.
.IP "" 4
.
.nf

States: RUNNING
valid options: schedule, hard
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
reboot \fIrange|vmid_list\fR Reboots the given VM, this is equivalent to execute the reboot command from the VM console\.
.
.IP "" 4
.
.nf

The VM will be ungracefully rebooted if \-\-hard is used\.

States: RUNNING
valid options: schedule, hard
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
deploy \fIrange|vmid_list\fR \fIhostid\fR [\fIdatastoreid\fR] Deploys the given VM in the specified Host\. This command forces the deployment, in a standard installation the Scheduler is in charge of this decision
.
.IP "" 4
.
.nf

States: PENDING, HOLD, STOPPED, UNDEPLOYED
valid options: enforce
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
migrate \fIrange|vmid_list\fR \fIhostid\fR [\fIdatastoreid\fR] Migrates the given running VM to another Host\. If used with \-\-live parameter the miration is done without downtime\.
.
.IP "" 4
.
.nf

States: RUNNING
valid options: enforce, live
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
stop \fIrange|vmid_list\fR Stops a running VM\. The VM state is saved and transferred back to the front\-end along with the disk files
.
.IP "" 4
.
.nf

States: RUNNING
valid options: schedule
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
suspend \fIrange|vmid_list\fR Saves a running VM\. It is the same as \'onevm stop\', but the files are left in the remote machine to later restart the VM there (i\.e\. the resources are not freed and there is no need to re\-schedule the VM)\.
.
.IP "" 4
.
.nf

States: RUNNING
valid options: schedule
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
resume \fIrange|vmid_list\fR Resumes the execution of the a saved VM
.
.IP "" 4
.
.nf

States: STOPPED, SUSPENDED, UNDEPLOYED, POWEROFF, UNKNOWN
valid options: schedule
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
recover \fIrange|vmid_list\fR Recovers a stuck VM that is waiting for a driver operation\. The recovery may be done by failing, succeeding or retrying the current operation\. YOU NEED TO MANUALLY CHECK THE VM STATUS ON THE HOST, to decide if the operation was successful or not, or if it can be retried\.
.
.IP "" 4
.
.nf

Example: A VM is stuck in "migrate" because of a hardware failure\. You
need to check if the VM is running in the new host or not to recover
the vm with \-\-success or \-\-failure, respectively\.

States for success/failure recovers: Any ACTIVE state\.
States for a retry recover: Any *FAILURE state
States for delete: Any
States for delete\-recreate: Any but STOP/UNDEPLOYED
valid options: success, failure, retry, interactive, delete, recreate
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
disk\-attach \fIvmid\fR Attaches a disk to a running VM\. When using \-\-file add only one DISK instance\.
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF
valid options: file, image, target, cache, discard, prefix
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
disk\-detach \fIvmid\fR \fIdiskid\fR Detaches a disk from a running VM
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
nic\-attach \fIvmid\fR Attaches a NIC to a running VM\. When using \-\-file add only one NIC instance\.
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF
valid options: file, network, ip
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
nic\-detach \fIvmid\fR \fInicid\fR Detaches a NIC from a running VM
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
chgrp \fIrange|vmid_list\fR \fIgroupid\fR Changes the VM group
.
.IP "\(bu" 4
chown \fIrange|vmid_list\fR \fIuserid\fR [\fIgroupid\fR] Changes the VM owner and group
.
.IP "\(bu" 4
chmod \fIrange|vmid_list\fR \fIoctet\fR Changes the VM permissions
.
.IP "\(bu" 4
resched \fIrange|vmid_list\fR Sets the rescheduling flag for the VM\.
.
.IP "" 4
.
.nf

States: RUNNING
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
unresched \fIrange|vmid_list\fR Clears the rescheduling flag for the VM\.
.
.IP "" 4
.
.nf

States: RUNNING
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
rename \fIvmid\fR \fIname\fR Renames the VM
.
.IP "\(bu" 4
snapshot\-create \fIrange|vmid_list\fR [\fIname\fR] Creates a new VM snapshot valid options: schedule
.
.IP "\(bu" 4
snapshot\-revert \fIvmid\fR \fIsnapshot_id\fR Reverts a VM to a saved snapshot
.
.IP "\(bu" 4
snapshot\-delete \fIvmid\fR \fIsnapshot_id\fR Delets a snapshot of a VM
.
.IP "\(bu" 4
disk\-snapshot\-create \fIvmid\fR \fIdiskid\fR \fIname\fR Takes a new snapshot of the given disk\. This operation needs support from the Datastore drivers: QCOW2 or Ceph\.
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF, SUSPENDED
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
disk\-snapshot\-revert \fIvmid\fR \fIdiskid\fR \fIsnapshot_id\fR Reverts disk state to a previously taken snapshot\.
.
.IP "" 4
.
.nf

States: POWEROFF, SUSPENDED
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
disk\-snapshot\-delete \fIvmid\fR \fIdiskid\fR \fIsnapshot_id\fR Deletes a disk snapshot\.
.
.IP "" 4
.
.nf

States: RUNNING, POWEROFF, SUSPENDED
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
list [\fIfilterflag\fR] Lists VMs in the pool valid options: list, listconf, delay, filter, csv, xml, numeric, kilobytes, describe
.
.IP "\(bu" 4
show \fIvmid\fR Shows information for the given VM valid options: xml, all
.
.IP "\(bu" 4
top [\fIfilterflag\fR] Lists Images continuously valid options: list, listconf, delay, filter, csv, xml, numeric, kilobytes
.
.IP "\(bu" 4
resize \fIvmid\fR Resizes the capacity of a Virtual Machine (offline, the VM cannot be RUNNING) valid options: cpu, vcpu, memory, enforce, file
.
.IP "\(bu" 4
save \fIvmid\fR \fIname\fR Clones the VM\'s source Template, replacing the disks with live snapshots of the current disks\. The VM capacity and NICs are also preserved
.
.IP "" 4
.
.nf

States: POWEROFF
valid options: persistent
.
.fi
.
.IP "" 0

.
.IP "\(bu" 4
updateconf \fIvmid\fR [\fIfile\fR] Updates the configuration of a VM\. The VM cannot be in an active (running) state, valid states are: pending, failure, poweroff, undeploy, hold or cloning\.
.
.IP "" 4
.
.nf

This command accepts a template file or opens an editor, the full list of
configuration attributes are:

OS       = ["ARCH", "MACHINE", "KERNEL", "INITRD", "BOOTLOADER", "BOOT"]
FEATURES = ["ACPI", "PAE", "APIC", "LOCALTIME", "HYPERV", "GUEST_AGENT"]
INPUT    = ["TYPE", "BUS"]
GRAPHICS = ["TYPE", "LISTEN", "PASSWD", "KEYMAP" ]
RAW      = ["DATA", "DATA_VMX", "TYPE"]
CONTEXT (any value, **variable substitution will be made**)
.
.fi
.
.IP "" 0

.
.IP "" 0
.
.SH "ARGUMENT FORMATS"
.
.IP "\(bu" 4
file Path to a file
.
.IP "\(bu" 4
range List of id\'s in the form 1,8\.\.15
.
.IP "\(bu" 4
text String
.
.IP "\(bu" 4
hostid OpenNebula HOST name or id
.
.IP "\(bu" 4
groupid OpenNebula GROUP name or id
.
.IP "\(bu" 4
userid OpenNebula USER name or id
.
.IP "\(bu" 4
datastoreid OpenNebula DATASTORE name or id
.
.IP "\(bu" 4
vmid OpenNebula VM name or id
.
.IP "\(bu" 4
vmid_list Comma\-separated list of OpenNebula VM names or ids
.
.IP "\(bu" 4
filterflag a, all all the known VMs m, mine the VM belonging to the user in ONE_AUTH g, group \'mine\' plus the VM belonging to the groups the user is member of uid VM of the user identified by this uid user VM of the user identified by the username
.
.IP "\(bu" 4
diskid Integer
.
.IP "" 0
.
.SH "LICENSE"
OpenNebula 5\.2\.0 Copyright 2002\-2016, OpenNebula Project, OpenNebula Systems
.
.P
Licensed under the Apache License, Version 2\.0 (the "License"); you may not use this file except in compliance with the License\. You may obtain a copy of the License at http://www\.apache\.org/licenses/LICENSE\-2\.0
